<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<link href="../../../assets/docs.css" rel="stylesheet" type="text/css" media="screen" />
<title>MooTools 1.3 Documentation - Request/Request</title>
</head>

<body>
  <div id="docs" class="doc">
    <div class="methods">
      <h4 class="menu-item"><a href="#Request">Request</a></h4>
      <div class="menu-item"><a href="#Request:setHeader">setHeader</a></div>
      <div class="menu-item"><a href="#Request:getHeader">getHeader</a></div>
      <div class="menu-item"><a href="#Request:send">send</a></div>
      <div class="menu-item"><a href="#Request:cancel">cancel</a></div>
      <div class="menu-item"><a href="#Request:isRunning">isRunning</a></div>
      <h4 class="menu-item"><a href="#Element-Properties">Element.Properties</a></h4>
      <div class="menu-item"><a href="#Element-Properties:send">send</a></div>
      <h4 class="menu-item"><a href="#Element">Element</a></h4>
      <div class="menu-item"><a href="#Element:send">send</a></div>
    </div>
    <div class="l-border r-border span-15 content">
      <h1 id="Request"><a href="#Request">Class: Request</a></h1>
      <p class="description">An XMLHttpRequest Wrapper.</p>
      <h3>Implements:</h3>
      <p><a href="../../../docs/core/Class/Class.Extras.html#Chain">Chain</a>, <a href="../../../docs/core/Class/Class.Extras.html#Events">Events</a>, <a href="../../../docs/core/Class/Class.Extras.html#Options">Options</a></p>
      <h3>Syntax:</h3>
      <pre class="javascript"><span class="kw2">var</span> myRequest = <span class="kw2">new</span> Request<span class="br0">(</span><span class="br0">[</span>options<span class="br0">]</span><span class="br0">)</span>;

</pre>
      <h3>Arguments:</h3>
      <ol>
        <li>options - (<em>object</em>, optional) See below.</li>
      </ol>
      <h3>Options:</h3>
      <ul>
        <li>url        - (<em>string</em>: defaults to null) The URL to request. (Note, this can also be an instance of <a href="../../../docs/more/Types/URI.html">URI</a>)</li>
        <li>method     - (<em>string</em>: defaults to 'post') The HTTP method for the request, can be either 'post' or 'get'.</li>
        <li>data       - (<em>string</em>: defaults to '') The default data for <a href="#Request:send">Request:send</a>, used when no data is given.</li>
        <li>link       - (<em>string</em>: defaults to 'ignore') Can be 'ignore', 'cancel' and 'chain'.
          <ul>
            <li>'ignore' - Any calls made to start while the request is running will be ignored. (Synonymous with 'wait': true from 1.11)</li>
            <li>'cancel' - Any calls made to start while the request is running will take precedence over the currently running request. The new request will start immediately, canceling the one that is currently running. (Synonymous with 'wait': false from 1.11)</li>
            <li>'chain'  - Any calls made to start while the request is running will be chained up, and will take place as soon as the current request has finished, one after another.</li>
          </ul>
        </li>
        <li>async      - (<em>boolean</em>: defaults to true) If set to false, the requests will be synchronous and freeze the browser during request.</li>
        <li>encoding   - (<em>string</em>: defaults to 'utf-8') The encoding to be set in the request header.</li>
        <li>headers    - (<em>object</em>) An object to use in order to set the request headers.</li>
        <li>isSuccess  - (<em>function</em>) Overrides the built-in isSuccess function.</li>
        <li>evalScripts  - (<em>boolean</em>: defaults to false) If set to true, <code>script</code> tags inside the response will be evaluated.</li>
        <li>evalResponse - (<em>boolean</em>: defaults to false) If set to true, the entire response will be evaluated. Responses with javascript content-type will be evaluated automatically.</li>
        <li>emulation  - (<em>boolean</em>: defaults to true) If set to true, other methods than 'post' or 'get' are appended as post-data named '_method' (used in rails)</li>
        <li>urlEncoded - (<em>boolean</em>: defaults to true) If set to true, the content-type header is set to www-form-urlencoded + encoding</li>
        <li>timeout - (<em>integer</em>: defaults to 0) In conjunction with <code>onTimeout</code> event, it determines the amount of milliseconds before considering a connection timed out. (It's suggested to not use timeout with big files and only when knowing what's expected.)</li>
        <li>noCache - (<em>boolean</em>; defaults to false) If <em>true</em>, appends a unique <em>noCache</em> value to the request to prevent caching. (IE has a bad habit of caching ajax request values. Including this script and setting the <em>noCache</em> value to true will prevent it from caching. The server should ignore the <em>noCache</em> value.)</li>
        <li>user - (<em>string</em>: defaults to undefined) When username is set the Request will open with credentials and try to authenticate.</li>
        <li>password - (<em>string</em>: defaults to undefined) You can use this option together with the <code>user</code> option to set authentication credentials when necessary. Note that the password will be passed as plain text and is therefore readable by anyone through the source code. It is therefore encouraged to use this option carefully</li>
      </ul>
      <h3>Events:</h3>
      <h4>request</h4>
      <p>Fired when the Request is sent.</p>
      <h5>Signature:</h5>
      <pre class="javascript">onRequest<span class="br0">(</span><span class="br0">)</span>
</pre>
      <h4>loadstart</h4>
      <p>Fired when the Request loaded, right before any progress starts. (This is limited to Browsers that support the event. At this time: Gecko and WebKit).</p>
      <h5>Signature:</h5>
      <pre class="javascript">onLoadstart<span class="br0">(</span>event, xhr<span class="br0">)</span>
</pre>
      <h5>Arguments:</h5>
      <ol>
        <li>event - (Event) The loadstart event.</li>
        <li>xhr - (XMLHttpRequest) The transport instance.</li>
      </ol>
      <h4>progress</h4>
      <p>Fired when the Request is making progresses in the download or upload. (This is limited to Browsers that support the event. At this time: Gecko and WebKit).</p>
      <h5>Signature:</h5>
      <pre class="javascript">onProgress<span class="br0">(</span>event, xhr<span class="br0">)</span>

</pre>
      <h5>Arguments:</h5>
      <ol>
        <li>event - (Event) The progress event, containing currently downloaded bytes and total bytes.</li>
        <li>xhr - (XMLHttpRequest) The transport instance.</li>
      </ol>
      <h3>Example:</h3>
      <pre class="javascript"><span class="kw2">var</span> myRequest = <span class="kw2">new</span> Request<span class="br0">(</span><span class="br0">{</span>

    url: <span class="st0">'image.jpg'</span>,
    onProgress: <span class="kw2">function</span><span class="br0">(</span>event, xhr<span class="br0">)</span> <span class="br0">{</span>
        <span class="kw2">var</span> loaded = event.<span class="me1">loaded</span>, total = event.<span class="me1">total</span>;

&nbsp;
        console.<span class="me1">log</span><span class="br0">(</span>parseInt<span class="br0">(</span>loaded / total * <span class="nu0">100</span>, <span class="nu0">10</span><span class="br0">)</span><span class="br0">)</span>;
    <span class="br0">}</span>
<span class="br0">}</span><span class="br0">)</span>;

&nbsp;
myRequest.<span class="me1">send</span><span class="br0">(</span><span class="br0">)</span>;
</pre>
      <h3>See Also:</h3>
      <ul>
        <li><a href="https://developer.mozilla.org/en/XPCOM_Interface_Reference/nsIDOMProgressEvent">MDC: nsIDOMProgressEvent</a></li>
      </ul>
      <h4>complete</h4>
      <p>Fired when the Request is completed.</p>
      <h5>Signature:</h5>
      <pre class="javascript">onComplete<span class="br0">(</span><span class="br0">)</span>
</pre>
      <h4>cancel</h4>
      <p>Fired when a request has been cancelled.</p>
      <h5>Signature:</h5>
      <pre class="javascript">onCancel<span class="br0">(</span><span class="br0">)</span>
</pre>
      <h4>success</h4>
      <p>Fired when the Request is completed successfully.</p>
      <h5>Signature:</h5>
      <pre class="javascript">onSuccess<span class="br0">(</span>responseText, responseXML<span class="br0">)</span>
</pre>
      <h5>Arguments:</h5>
      <ol>
        <li>responseText - (<em>string</em>) The returned text from the request.</li>
        <li>responseXML  - (<em>mixed</em>) The response XML from the request.</li>
      </ol>
      <h4>failure</h4>
      <p>Fired when the request failed (error status code).</p>
      <h5>Signature:</h5>
      <pre class="javascript">onFailure<span class="br0">(</span>xhr<span class="br0">)</span>
</pre>
      <h5>Arguments:</h5>
      <p>xhr - (XMLHttpRequest) The transport instance.</p>
      <h4>exception</h4>
      <p>Fired when setting a request header fails.</p>
      <h5>Signature:</h5>
      <pre class="javascript">onException<span class="br0">(</span>headerName, value<span class="br0">)</span>

</pre>
      <h5>Arguments:</h5>
      <ol>
        <li>headerName - (<em>string</em>) The name of the failing header.</li>
        <li>value      - (<em>string</em>) The value of the failing header.</li>
      </ol>
      <h3>Properties:</h3>
      <ul>
        <li>response - (<em>object</em>) Object with text and XML as keys. You can access this property in the 'success' event.</li>
      </ul>
      <h3>Returns:</h3>
      <ul>
        <li>(<em>object</em>) A new Request instance.</li>
      </ul>
      <h3>Example:</h3>
      <pre class="javascript"><span class="kw2">var</span> myRequest = <span class="kw2">new</span> Request<span class="br0">(</span><span class="br0">{</span>method: <span class="st0">'get'</span>, url: <span class="st0">'requestHandler.php'</span><span class="br0">}</span><span class="br0">)</span>;
myRequest.<span class="me1">send</span><span class="br0">(</span><span class="st0">'name=john&amp;lastname=dorian'</span><span class="br0">)</span>;

</pre>
      <h3>See Also:</h3>
      <ul>
        <li><a href="http://en.wikipedia.org/wiki/XMLHttpRequest">Wikipedia: XMLHttpRequest</a></li>
      </ul>
      <h4>timeout</h4>
      <p>Fired when a request doesn't change state for <code>options.timeout</code> milliseconds.</p>
      <h5>Signature:</h5>
      <pre class="javascript">onTimeout<span class="br0">(</span><span class="br0">)</span>
</pre>
      <h2 id="Request:setHeader"><a href="#Request:setHeader">Request Method: setHeader</a></h2>
      <p class="description">Add or modify a header for the request. It will not override headers from the options.</p>
      <h3>Syntax:</h3>
      <pre class="javascript">myRequest.<span class="me1">setHeader</span><span class="br0">(</span><span class="kw3">name</span>, value<span class="br0">)</span>;
</pre>
      <h3>Arguments:</h3>
      <ol>
        <li>name  - (<em>string</em>) The name for the header.</li>
        <li>value - (<em>string</em>) The value to be assigned.</li>
      </ol>
      <h3>Returns:</h3>
      <ul>
        <li>(<em>object</em>) This Request instance.</li>
      </ul>
      <h3>Example:</h3>
      <pre class="javascript"><span class="kw2">var</span> myRequest = <span class="kw2">new</span> Request<span class="br0">(</span><span class="br0">{</span>url: <span class="st0">'getData.php'</span>, method: <span class="st0">'get'</span>, headers: <span class="br0">{</span><span class="st0">'X-Request'</span>: <span class="st0">'JSON'</span><span class="br0">}</span><span class="br0">}</span><span class="br0">)</span>;
myRequest.<span class="me1">setHeader</span><span class="br0">(</span><span class="st0">'Last-Modified'</span>,<span class="st0">'Sat, 1 Jan 2005 05:00:00 GMT'</span><span class="br0">)</span>;

</pre>
      <h2 id="Request:getHeader"><a href="#Request:getHeader">Request Method: getHeader</a></h2>
      <p class="description">Returns the given response header or null if not found.</p>
      <h3>Syntax:</h3>
      <pre class="javascript">myRequest.<span class="me1">getHeader</span><span class="br0">(</span><span class="kw3">name</span><span class="br0">)</span>;

</pre>
      <h3>Arguments:</h3>
      <ol>
        <li>name - (<em>string</em>) The name of the header to retrieve the value of.</li>
      </ol>
      <h3>Returns:</h3>
      <ul>
        <li>(<em>string</em>) The value of the retrieved header.</li>
        <li>(<em>null</em>) <code>null</code> if the header is not found.</li>
      </ul>
      <h3>Example:</h3>
      <pre class="javascript"><span class="kw2">var</span> myRequest = <span class="kw2">new</span> Request<span class="br0">(</span><span class="br0">{</span>url: <span class="st0">'getData.php'</span>, method: <span class="st0">'get'</span>, onSuccess: <span class="kw2">function</span><span class="br0">(</span>responseText, responseXML<span class="br0">)</span> <span class="br0">{</span>

    <span class="kw3">alert</span><span class="br0">(</span><span class="kw1">this</span>.<span class="me1">getHeader</span><span class="br0">(</span><span class="st0">'Date'</span><span class="br0">)</span><span class="br0">)</span>; <span class="co1">// alerts the server date (for example, 'Thu, 26 Feb 2009 20:26:06 GMT')</span>
<span class="br0">}</span><span class="br0">}</span><span class="br0">)</span>;

</pre>
      <h2 id="Request:send"><a href="#Request:send">Request Method: send</a></h2>
      <p class="description">Opens the Request connection and sends the provided data with the specified options.</p>
      <h3>Syntax:</h3>
      <pre class="javascript">myRequest.<span class="me1">send</span><span class="br0">(</span><span class="br0">[</span>options<span class="br0">]</span><span class="br0">)</span>;

</pre>
      <h3>Arguments:</h3>
      <ol>
        <li>options - (<em>object</em>, optional) The options for the sent Request.  Will also accept data as a query string for compatibility reasons.</li>
      </ol>
      <h3>Returns:</h3>
      <ul>
        <li>(<em>object</em>) This Request instance.</li>
      </ul>
      <h3>Examples:</h3>
      <pre class="javascript"><span class="kw2">var</span> myRequest = <span class="kw2">new</span> Request<span class="br0">(</span><span class="br0">{</span>url: <span class="st0">'http://localhost/some_url'</span><span class="br0">}</span><span class="br0">)</span>.<span class="me1">send</span><span class="br0">(</span><span class="st0">'save=username&amp;name=John'</span><span class="br0">)</span>;

</pre>
      <h3>Notes:</h3>
      <p>MooTools provides several aliases for <a href="#Request:send">Request:send</a> to make it easier to use different methods. These aliases are post() and POST(), get() and GET(), put() and PUT() and delete() and DELETE().</p>
      <pre class="javascript"><span class="kw2">var</span> myRequest = <span class="kw2">new</span> Request<span class="br0">(</span><span class="br0">{</span>url: <span class="st0">'http://localhost/some_url'</span><span class="br0">}</span><span class="br0">)</span>;

&nbsp;
myRequest.<span class="me1">post</span><span class="br0">(</span><span class="st0">'save=username&amp;name=John'</span><span class="br0">)</span>;
<span class="co1">//...is equivalent to:</span>
myRequest.<span class="me1">send</span><span class="br0">(</span><span class="br0">{</span>
    method: <span class="st0">'post'</span>,
    data: <span class="st0">'save=username&amp;name=John'</span>

<span class="br0">}</span><span class="br0">)</span>;
&nbsp;
myRequest.<span class="me1">get</span><span class="br0">(</span><span class="st0">'save=username&amp;name=John'</span><span class="br0">)</span>;
<span class="co1">//...is equivalent to:</span>
myRequest.<span class="me1">send</span><span class="br0">(</span><span class="br0">{</span>

    method: <span class="st0">'get'</span>,
    data: <span class="st0">'save=username&amp;name=John'</span>
<span class="br0">}</span><span class="br0">)</span>;
</pre>
      <h2 id="Request:cancel"><a href="#Request:cancel">Request Method: cancel</a></h2>
      <p class="description">Cancels the currently running request, if any.</p>
      <h3>Syntax:</h3>
      <pre class="javascript">myRequest.<span class="me1">cancel</span><span class="br0">(</span><span class="br0">)</span>;
</pre>
      <h3>Returns:</h3>
      <ul>
        <li>(<em>object</em>) This Request instance.</li>
      </ul>
      <h3>Example:</h3>
      <pre class="javascript"><span class="kw2">var</span> myRequest = <span class="kw2">new</span> Request<span class="br0">(</span><span class="br0">{</span>url: <span class="st0">'mypage.html'</span>, method: <span class="st0">'get'</span><span class="br0">}</span><span class="br0">)</span>.<span class="me1">send</span><span class="br0">(</span><span class="st0">'some=data'</span><span class="br0">)</span>;
myRequest.<span class="me1">cancel</span><span class="br0">(</span><span class="br0">)</span>;

</pre>
      <h2 id="Request:isRunning"><a href="#Request:isRunning">Request Method: isRunning</a></h2>
      <p class="description">Returns true if the request is currently running</p>
      <h3>Syntax:</h3>
      <pre class="javascript">myRequest.<span class="me1">isRunning</span><span class="br0">(</span><span class="br0">)</span>
</pre>
      <h3>Returns:</h3>
      <ul>
        <li>(<em>boolean</em>) True if the request is running</li>
      </ul>
      <h3>Example:</h3>
      <pre class="javascript"><span class="kw2">var</span> myRequest = <span class="kw2">new</span> Request<span class="br0">(</span><span class="br0">{</span>url: <span class="st0">'mypage.html'</span>, method: <span class="st0">'get'</span><span class="br0">}</span><span class="br0">)</span>.<span class="me1">send</span><span class="br0">(</span><span class="st0">'some=data'</span><span class="br0">)</span>;

&nbsp;
<span class="kw1">if</span> <span class="br0">(</span>myRequest.<span class="me1">isRunning</span><span class="br0">(</span><span class="br0">)</span><span class="br0">)</span> <span class="co1">// It runs!</span>
</pre>
      <h1 id="Element-Properties"><a href="#Element-Properties">Object: Element.Properties</a></h1>
      <p class="description">see <a href="../../../docs/core/Element/Element.html#Element-Properties">Element.Properties</a></p>
      <h2 id="Element-Properties:send"><a href="#Element-Properties:send">Element Property: send</a></h2>
      <h3 class="description">Setter</h3>
      <p>Sets a default Request instance for an Element.  This is useful when handling forms.</p>
      <h4>Syntax:</h4>
      <pre class="javascript">el.<span class="me1">set</span><span class="br0">(</span><span class="st0">'send'</span><span class="br0">[</span>, options<span class="br0">]</span><span class="br0">)</span>;

</pre>
      <h4>Arguments:</h4>
      <ol>
        <li>options - (<em>object</em>) The Request options.</li>
      </ol>
      <h4>Returns:</h4>
      <ul>
        <li>(<em>element</em>) The original element.</li>
      </ul>
      <h4>Example:</h4>
      <pre class="javascript">myForm.<span class="me1">set</span><span class="br0">(</span><span class="st0">'send'</span>, <span class="br0">{</span>url: <span class="st0">'contact.php'</span>, method: <span class="st0">'get'</span><span class="br0">}</span><span class="br0">)</span>;
myForm.<span class="me1">send</span><span class="br0">(</span><span class="br0">)</span>; <span class="co1">//Sends the form.</span>

</pre>
      <h3>Getter</h3>
      <p>Returns the previously set Request instance (or a new one with default options).</p>
      <h4>Syntax:</h4>
      <pre class="javascript">el.<span class="me1">get</span><span class="br0">(</span><span class="st0">'send'</span><span class="br0">)</span>;

</pre>
      <h4>Arguments:</h4>
      <ol>
        <li>property - (<em>string</em>) the Request property argument.</li>
      </ol>
      <h3>Returns:</h3>
      <ul>
        <li>(<em>object</em>) The Request instance.</li>
      </ul>
      <h4>Example:</h4>
      <pre class="javascript">el.<span class="me1">get</span><span class="br0">(</span><span class="st0">'send'</span>, <span class="br0">{</span>method: <span class="st0">'get'</span><span class="br0">}</span><span class="br0">)</span>;
el.<span class="me1">send</span><span class="br0">(</span><span class="br0">)</span>;
el.<span class="me1">get</span><span class="br0">(</span><span class="st0">'send'</span><span class="br0">)</span>; <span class="co1">// returns the Request instance.</span>

</pre>
      <h1 id="Element"><a href="#Element">Type: Element</a></h1>
      <p class="description">Custom Type to allow all of its methods to be used with any DOM element via the dollar function <a href="../../../docs/core/Element/Element.html#Window:dollar">$</a>.</p>
      <h2 id="Element:send"><a href="#Element:send">Element Method: send</a></h2>
      <p class="description">Sends a form or a container of inputs with an HTML request.</p>
      <h3>Syntax:</h3>
      <pre class="javascript">myElement.<span class="me1">send</span><span class="br0">(</span>url<span class="br0">)</span>;
</pre>
      <h3>Arguments:</h3>
      <ol>
        <li>url - (<em>string</em>, optional) The url you want to send the form or the "container of inputs" to. If url is omitted, the action of the form will be used. url cannot be omitted for "container of inputs".</li>
      </ol>
      <h3>Returns:</h3>
      <ul>
        <li>(element) This Element.</li>
      </ul>
      <h3>Example:</h3>
      <h5>HTML</h5>
      <pre class="javascript">&lt;form id=<span class="st0">"myForm"</span> action=<span class="st0">"submit.php"</span>&gt;

    &lt;p&gt;
        &lt;input <span class="kw3">name</span>=<span class="st0">"email"</span> value=<span class="st0">"bob@bob.com"</span> /&gt;
        &lt;input <span class="kw3">name</span>=<span class="st0">"zipCode"</span> value=<span class="st0">"90210"</span> /&gt;

    &lt;/p&gt;
&lt;/form&gt;
</pre>
      <h5>JavaScript</h5>
      <pre class="javascript">$<span class="br0">(</span><span class="st0">'myForm'</span><span class="br0">)</span>.<span class="me1">send</span><span class="br0">(</span><span class="br0">)</span>;

</pre>
      <h3>Note:</h3>
      <ul>
        <li>The URL is taken from the action attribute of the form.</li>
      </ul>
    </div>
  </div>
<script type="text/javascript" src="../../../assets/mootools-core-1.3.js"></script>
<script type="text/javascript" src="../../../assets/mootools-more-smoothscroll.js"></script>
<script type="text/javascript" src="../../../assets/doc-assist.js"></script>
</body>
</html>
